.\"-
.\" Copyright (c) 2006 Verdens Gang AS
.\" Copyright (c) 2006 Linpro AS
.\" All rights reserved.
.\"
.\" Author: Dag-Erling Smørgrav <des@linpro.no>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $Id: varnishd.1 1458 2007-05-20 17:38:15Z des $
.\"
.Dd May 16, 2007
.Dt VARNISHD 1
.Os
.Sh NAME
.Nm varnishd
.Nd HTTP accelerator daemon
.Sh SYNOPSIS
.Nm
.Op Fl a Ar addrss Ns Op : Ns Ar port
.Op Fl b Ar host Ns Op : Ns Ar port
.Op Fl d
.Op Fl f Ar config
.Op Fl h Ar type Ns Op , Ns Ar options
.Op Fl P Ar file
.Op Fl p Ar param Ns = Ns Ar value
.Op Fl s Ar type Ns Op , Ns Ar options
.Op Fl T Ar address Ns Op : Ns Ar port
.Op Fl t Ar ttl
.Op Fl V
.Op Fl w Ar min Ns Op , Ns Ar max Ns Op , Ns Ar timeout
.Sh DESCRIPTION
The
.Nm
daemon accepts HTTP requests from clients, passes them on to a backend
server and caches the returned documents to better satisfy future
requests for the same document.
.Pp
The following options are available:
.Bl -tag -width Fl
.It Fl a Ar address Ns Op : Ns Ar port
Listen for client requests on the specified
.Ar address
and
.Ar port .
The
.Ar address
can be a host name
.Pq Dq localhost ,
an IPv4 dotted-quad
.Pq Dq 127.0.0.1 ,
or an IPv6 address enclosed in square brackets
.Pq Dq [::1] .
If
.Ar address
is not specified,
.Nm
will listen on all available IPv4 and IPv6 interfaces.
If
.Ar port
is not specified, the default HTTP port as listed in
.Pa /etc/services
is used.
.It Fl b Ar host Ns Op : Ns Ar port
Use the specified
.Ar host
as backend server.
If
.Ar port
is not specified, the default is 8080.
.It Fl d
Enables debugging mode.
This causes
.Nm
to fork; the child process daemonizes and runs as usual, while the
parent process remains attached to the console and will accept
management commands from
.Dv stdin .
If the parent process receives
.Dv EOF ,
it will terminate, but the child process will continue to run.
.Pp
The child process will not start accepting client connections until
the
.Cm start
command is given.
.Pp
If the
.Fl d
flag is specified twice, the child process will not daemonize, and
terminating the parent process will also terminate the child.
.It Fl f Ar config
Use the specified VCL configuration file instead of the builtin
default.
See
.Xr vcl 7
for details on VCL syntax.
.It Fl h Ar type Ns Op , Ns Ar options
Specifies the hash algorithm.
See
.Sx Hash Algorithms
for a list of supported algorithms.
.It Fl P Ar file
Write the process's PID to the specified
.Ar file .
.It Fl p Ar param Ns = Ns Ar value
Set the parameter specified by
.Ar param
to the specified
.Ar value .
See
.Sx Run-Time Parameters
for a list of parameters.
.It Fl s Ar type Ns Op , Ns Ar options
Use the specified storage backend.
See
.Sx Storage Types
for a list of supported storage types.
.It Fl T Ar address Ns Op : Ns Ar port
Offer a management interface on the specified
.Ar address
and
.Ar port .
See
.Sx Management Interface
for a list of management commands.
.It Fl t Ar ttl
Specifies a hard minimum time to live for cached documents.
This is a shortcut for specifying the
.Va default_ttl
run-time parameter.
.It Fl V
Display the version number and exit.
.It Fl w Ar min Ns Op , Ns Ar max Ns Op , Ns Ar timeout
Start at least
.Ar min
but no more than
.Ar max
worker threads with the specified idle timeout.
This is a shortcut for specifying the
.Va thread_pool_min ,
.Va thread_pool_max
and
.Va thread_pool_timeout
run-time parameters.
.Pp
If only one number is specified,
.Va thread_pool_min
and
.Va thread_pool_max
are both set to this number, and
.Va thread_pool_timeout
has no effect.
.El
.Ss Hash Algorithms
The following hash algorithms are available:
.Bl -tag -width 4n
.It Cm simple_list
A simple doubly-linked list.
Not recommended for production use.
.It Cm classic Ns Op Ns , Ns Ar buckets
A standard hash table.
This is the default.
.Pp
The hash key is the CRC32 of the object's URL modulo the size of the
hash table.
Each table entry points to a list of elements which share the same
hash key.
.Pp
The
.Ar buckets
parameter specifies the number of entries in the hash table.
The default is 16383.
.El
.Ss Storage Types
The following storage types are available:
.Bl -tag -width 4n
.It Cm malloc
Storage for each object is allocated with
.Xr malloc 3 .
Not recommended for production use.
.It Cm file Ns Op Ns , Ns Ar path Ns Op Ns , Ns Ar size
Storage for each object is allocated from an arena backed by a file.
This is the default.
.Pp
The
.Ar path
parameter specifies either the path to the backing file or the path to
a directory in which
.Nm
will create the backing file.
The default is
.Pa /tmp .
.Pp
The
.Ar size
parameter specifies the size of the backing file.
The size is assumed to be in bytes, unless followed by one of the
following suffixes:
.Bl -tag -width indent
.It K, k
The size is expressed in kibibytes.
.It M, m
The size is expressed in mebibytes.
.It G, g
The size is expressed in gibibytes.
.It T, t
The size is expressed in tebibytes.
.It %
The size is expressed as a percentage of the free space on the file
system where it resides.
.El
.Pp
The default size is 50%.
.Pp
If the backing file already exists, it will be truncated or expanded
to the specified size.
.Pp
Note that if
.Nm
has to create or expand the file, it will not pre-allocate the added
space, leading to fragmentation, which may adversely impact
performance.
Pre-creating the storage file using
.Xr dd 1
will reduce fragmentation to a minimum.
.El
.Ss Management Interface
If the
.Fl -T
option was specified,
.Nm
will offer a command-line management interface on the specified
address and port.
The following commands are available:
.Bl -tag -width 4n
.It Cm dump.pool
.It Cm help
Display a list of available commands.
.It Cm param.set Ar param Ar value
Set the parameter specified by
.Ar param
to the specified
.Ar value .
See
.Sx Run-Time Parameters
for a list of parameters.
.It Cm param.show Ar param
Display the value of the parameter specified by
.Ar param .
See
.Sx Run-Time Parameters
for a list of parameters.
.It Cm param.show Op Fl l
Display a list of run-time parameters and their values.
If the
.Fl l
option is specified, the list includes a brief explanation of each
parameter.
.It Cm ping Op Ns Ar timestamp
Ping the child process.
.It Cm start
Start the child process if it is not already running.
.It Cm stats
Display server statistics.
All the numbers presented are totals since server startup; for a
better idea of the current situation, use the
.Xr varnishstat 1
utility.
.It Cm stop
Stop the child process.
.It Cm url.purge Ar regexp
Immediately invalidate all documents whos URL matches the specified
regular expression.
.It Cm vcl.discard Ar configname
Discard the configuration specified by
.Ar configname .
This will have no effect if the specified configuration has a non-zero
reference count.
.It Cm vcl.inline Ar configname Ar vcl
Create a new configuration named
.Ar configname
with the VCL code specified by
.Ar vcl ,
which must be a quoted string.
.It Cm vcl.list
List available configurations and their respective reference counts.
The active configuration is indicated with an asterisk ("*").
.It Cm vcl.load Ar configname Ar filename
Create a new configuration named
.Ar configname
with the contents of the specified file.
.It Cm vcl.use Ar configname
Start using the configuration specified by
.Ar configname
for all new requests.
Existing requests will continue using whichever configuration was in
use when they arrived.
.El
.Ss Run-Time Parameters
.\" Keep in synch with parspec[] in mgt_param.c
.Bl -tag -width 4n
.It Va auto_restart
Whether to automatically restart the child process if it dies.
.Pp
The default is
.Dv on .
.It Va backend_http11
Whether to force the use of HTTP/1.1 when requesting documents from
the server, or just use the same protocol version as the client which
triggered the retrieval.
.Pp
The default is
.Dv off .
.It Va client_http11
Whether to force the use of HTTP/1.1 when responding to client
requests, or just use the same protocol version as that used by the
backend server which delivered the requested document.
.Pp
The default is
.Dv off .
.It Va default_ttl
The default time-to-live assigned to objects if neither the backend
nor the configuration assign one.
Note that changes to this parameter are not applied retroactively.
.Pp
The default is 120 seconds.
.It Va fetch_chunksize
The default chunk size used when retrieving documents for which the
backend server does not specify a content length.
.Pp
The default is 128 kilobytes.
.It Va http_workspace
The size of the per-session workspace for HTTP protocol data.
For performance reasons, this space is preallocated, so any change to
this parameter will only apply to new client sessions.
.Pp
The default is 8192 bytes.
.It Va listen_address
The address at which to listen for client connections.
Changes to this parameter will only take effect when the child process
is restarted.
.Pp
The default is 0.0.0.0:80.
.It Va listen_depth
The depth of the TCP listen queue.
.Pp
The default is 512.
.It Va overflow_max
The maximum depth of the overflow queue as a percentage of
.Va thread_pool_max .
The overflow queue holds requests waiting for a worker thread to
become available.
If the overflow queue fills up,
.Nm
will start dropping new connections.
.Pp
The default is 100%.
.It Va ping_interval
The interval at which the parent process will ping the child process
to ascertain that it is still present and functioning.
.Pp
The default is 3 seconds.
.It Va pipe_timeout
The time to wait before dropping an idle pipe mode connection.
.Pp
The default is 60 seconds.
.It Va sendfile_threshold
The size threshold beyond which documents are sent to the client using
.Xr sendfile 2
instead of
.Xr writev 2 .
This is not likely to have any effect unless the working set is too
large to fit in physical memory.
.Pp
Note that several operating systems have known bugs which make it
inadvisable to use this.
.Pp
The default is -1, which disables the use of sendfile altogether.
.It Va send_timeout
The time to wait before dropping the connection to a client which is
not accepting data sent to it.
.Pp
The default is 600 seconds.
.It Va sess_timeout
The time to wait before dropping an idle client session.
.Pp
The default is 5 seconds.
.It Va srcaddr_hash
The size of the hash table used to store per-client accounting data.
This should preferably be a prime number.
.Pp
The default is 1049.
.It Va srcaddr_ttl
The length of time to keep per-client accounting records.
Setting this to 0 will disable per-client accounting.
.It Va thread_pool_max
The maximum total number of worker threads.
If the number of concurrent requests rises beyond this number,
requests will start queueing up waiting for a worker thread to pick
them up.
Higher values may improve response time but will increase pressure on
the scheduler.
.Pp
The default is 1000.
.It Va thread_pool_min
The minimum total number of worker threads.
Higher values may allow
.Nm
to respond faster to a sudden increase in traffic.
.Pp
The default is 1.
.It Va thread_pools
The number of worker thread pools.
Higher values reduce lock contention but increase pressure on the
scheduler.
Note that a decrease of this parameter will only take effect after a
restart.
.Pp
The default is 1.
.It Va thread_pool_timeout
The amount of time a worker thread can be idle before it is killed,
when the number of worker threads exceeds
.Va thread_pool_min .
.Pp
The default is 120 seconds.
.It Va vcl_trace
Whether to issue log entries for calls to VCL code and their results.
Note that this will generate large amounts of log data.
.Pp
The default is
.Dv off .
.El
.Sh SEE ALSO
.Xr varnishlog 1 ,
.Xr varnishhist 1 ,
.Xr varnishncsa 1 ,
.Xr varnishstat 1 ,
.Xr varnishtop 1 ,
.Xr vcl 7
.\" .Sh STANDARDS
.\" .Rs
.\" .%A R. Fielding
.\" .%A J. Gettys
.\" .%A J. Mogul
.\" .%A H. Frystyk
.\" .%A L. Masinter
.\" .%A P. Leach
.\" .%A T. Berners-Lee
.\" .%D January 1999
.\" .%B Hypertext Transfer Protocol -- HTTP/1.1
.\" .%O RFC2616
.Sh HISTORY
The
.Nm
daemon was developed by
.An Poul-Henning Kamp Aq phk@phk.freebsd.dk
in cooperation with Verdens Gang AS and Linpro AS.
This manual page was written by
.An Dag-Erling Sm\(/orgrav Aq des@linpro.no .
